/**
 *
 * Copyright 2009 Bill Garrett (memesis@gmail.com)
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use
 * this file except in compliance with the License.  You may obtain a copy of the
 * License at
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software distributed
 * under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
 * CONDITIONS OF ANY KIND, either express or implied. See the License for the specific
 * language governing permissions and limitations under the License. 
 */
package org.memesis.pandorasbook;

import java.net.MalformedURLException;
import java.util.Map;

/**
 * Implement this interface if you can run an applet within a Storybook frame.
 *
 * @author garrett
 */
public interface PandoraApplet {
	/**
	 * Applets support a mapping of property names and values which are initialized when the app starts.
	 * 
	 * @return a read/write map of key-value pairs
	 */
	public Map<String, String> getProperties();

	
	/**
	 *  Set the Applet's desktop attribute to allow it to interact with the desktop.
	 * 
	 * @param desk - desktop instance to set
	 */
	public void setDesktop(PandoraDesktop desk);
	
	/**
	 * Run another applet in this desktop.
	 * 
	 * @return - the applet in question.
	 * @throws MalformedURLException 
	 */
	public PandoraApplet runApplet(String url) throws MalformedURLException;
	public PandoraApplet runApplet(String url, Map<String, String> newProps) throws MalformedURLException;
	
	/**
	 * A convenience method to retrieve an applet's key value, or null if the key does not exist.
	 * 
	 * @param key the key to search for
	 * @return the property value, or null
	 */
	public String getProperty(String key);
	
	/**
	 * Called when the desktop is ready to begin executing the applet.
	 */
	public void startApplet(PandoraAppletFrame frame);
	
	/**
	 * Called when the desktop needs to shut down the applet for some reason.
	 */
	public void stopApplet();
}
